home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / ICON / ICONV8 / Docs / Tr90-3 < prev    next >
Text File  |  1990-07-19  |  13KB  |  529 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.               Personalized Interpreters for Version
  15.                            8 of Icon*
  16.  
  17.  
  18.                         Ralph E. Griswold
  19.  
  20.  
  21.  
  22.  
  23.                             TR 90-3a
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.          January 1, 1990; last revised Feburary 13, 1990
  50.  
  51.  
  52.                  Department of Computer Science
  53.  
  54.                     The University of Arizona
  55.  
  56.                       Tucson, Arizona 85721
  57.  
  58.  
  59.  
  60.  
  61. *This work was supported by the National Science Foundation under
  62. Grant CCR-8713690.
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.               Personalized Interpreters for Version
  77.                             8 of Icon
  78.  
  79.  
  80.  
  81.  
  82. 1.__Introduction
  83.  
  84.    Despite the fact that the Icon programming language has a
  85. large repertoire of functions and operations for string and list
  86. manipulation, as well as for more conventional computations
  87. [1,2], some users need to extend that repertoire. While many
  88. extensions can be written as procedures that build on the exist-
  89. ing repertoire, there are some kinds of extensions for which this
  90. approach is unacceptably inefficient, inconvenient, or simply
  91. impractical.
  92.  
  93.    Icon itself is written C and its built-in functions are writ-
  94. ten as corresponding C functions. Thus, the natural way to extend
  95. Icon's computational repertoire is to add new C functions to it.
  96.  
  97.    The Icon system is organized so that this is comparatively
  98. easy to do.  Adding new functions does not require changes to the
  99. Icon grammar, since all functions have a common syntactic form.
  100. An entry must be made in an array that identifies built-in func-
  101. tions and connects references to them to the code itself.
  102.  
  103.    One method of adding new functions to Icon is to add the
  104. corresponding C functions to the Icon system itself and to
  105. rebuild the entire system.  If the extensions are not of general
  106. interest, it is inappropriate to include them in the public ver-
  107. sion of Icon. On the other hand, Icon is a large and complicated
  108. system, and having many private versions may create serious prob-
  109. lems of maintenance and disk usage. Furthermore, rebuilding the
  110. Icon system is time-consuming. This approach may be impractical,
  111. for example, in a situation such as a class in which students
  112. implement their own versions of an extension.
  113.  
  114.    To remedy these problems, a mechanism for building ``personal-
  115. ized interpreters'' is included in UNIX* implementations of Icon.
  116. This mechanism allows a user to add C functions and to build a
  117. corresponding interpreter quickly, easily, and without the neces-
  118. sity to have a copy of the source code for the entire Icon sys-
  119. tem.
  120.  
  121.    To construct a personalized interpreter, the user must perform
  122. a one-time set up that copies relevant source files to a direc-
  123. tory specified by the user and builds the nucleus of a run-time
  124. __________________________
  125. *UNIX is a trademark of AT&T Bell Laboratories.
  126.  
  127.  
  128.  
  129.  
  130.                               - 1 -
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. system. Once this is done, the user can add and modify C func-
  140. tions and include them in the personalized run-time system with
  141. little effort.
  142.  
  143.    The modifications that can be made to Icon via a personalized
  144. interpreter essentially are limited to the run-time system: the
  145. addition of new functions, and modifications to existing func-
  146. tions, operations, and support routines. There is no provision
  147. for changing the syntax of Icon or for incorporating new opera-
  148. tors, keywords, and control structures.
  149.  
  150.  
  151. 2.__Building_and_Using_a_Personalized_Interpreter
  152.  
  153. 2.1__Setting_Up_a_Personalized_Interpreter_System
  154.  
  155.    To set up a personalized interpreter, a new directory should
  156. be created solely for the use of the interpreter; otherwise files
  157. may be accidentally destroyed by the set-up process.  For the
  158. purpose of example, suppose this directory is named myicon. The
  159. set-up consists of
  160.  
  161.         mkdir myicon
  162.         cd myicon
  163.         icon_pi
  164.  
  165. Note that icon_pi must be run when in the area in which the per-
  166. sonalized interpreter is to be built.  The location of icon_pi
  167. may vary from site to site.
  168.  
  169.    The shell script icon_pi constructs four subdirectories: h,
  170. common, std, and pi. The subdirectory h contains header files
  171. that are needed in C routines.  The subdirectory common contains
  172. files common to several components of Icon.  The subdirectory std
  173. contains the machine-independent portions of the Icon system that
  174. are needed to build a personalized interpreter.  The subdirectory
  175. pi contains a Makefile for building a personalized interpreter
  176. and also is the place where source code for new C functions nor-
  177. mally resides. Thus, work on the personalized interpreter is done
  178. in myicon/pi.
  179.  
  180.    The Makefile that is constructed by icon_pi contains two
  181. definitions to facilitate building personalized interpreters:
  182.  
  183.      OBJS a list of object modules that are to be added to or
  184.           replaced in the run-time system. OBJS initially is
  185.           empty.
  186.  
  187.      LIB  a list of library options that are used when the run-
  188.           time system is built. LIB initially is empty, but the
  189.           math library is loaded as a normal part of building the
  190.           run-time system.
  191.  
  192. See the listing of the generic version of this Makefile in the
  193.  
  194.  
  195.  
  196.                               - 2 -
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205. appendix of this report.
  206.  
  207. 2.2__Building_a_Personalized_Interpreter
  208.  
  209.    Performing a
  210.  
  211.         make pi
  212.  
  213. in myicon/pi creates two files in myicon:
  214.  
  215.         picont     command processor
  216.         piconx     run-time system
  217.  
  218. Links to these files also are constructed in myicon/pi so that
  219. the new personalized interpreter can be tested in the directory
  220. in which it is made.
  221.  
  222.    The user of the personalized interpreter uses picont in the
  223. same fashion that the standard icont is used.  (Note that the
  224. accidental use of icont in place of picont may produce mysterious
  225. results.)
  226.  
  227.    The relocation bits and symbols in piconx can be removed by
  228.  
  229.         make Stripx
  230.  
  231. in myicon/pi. This reduces the size of this file substantially
  232. but may interfere with debugging.
  233.  
  234.    If a make is performed in myicon/pi before any run-time files
  235. are added or modified, the resulting personalized interpreter is
  236. identical to the standard one. Such a make can be performed to
  237. verify that the personalized interpreter system is performing
  238. properly.
  239.  
  240. 2.3__Version_Numbering
  241.  
  242.    The Icon run-time system checks an identifying version number
  243. to be sure the output of picont corresponds to piconx. The ver-
  244. sion number is the string defined for IVersion in
  245. myicon/h/version.h following the construction of a personalized
  246. interpreter as described in Section 2.1.
  247.  
  248.    In order to assure that files produced by picont can only be
  249. run by the current versions of piconx, the value of IVersion
  250. should be changed whenever a change is made to a personalized
  251. interpreter. It is not important what the definition of IVersion
  252. is, so long as it is a short string that is different from those
  253. for other versions of Icon.
  254.  
  255. 2.4__Adding_New_Functions
  256.  
  257.    To add new functions to the personalized interpreter, it is
  258. first necessary to provide the C code for them, adhering to the
  259.  
  260.  
  261.  
  262.                               - 3 -
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271. conventions and data structures used throughout Icon [3,4].  The
  272. directory src/iconx in the Version 8 Icon hierarchy contains the
  273. source code for the standard functions, which can be used as
  274. models for new ones.
  275.  
  276.    Suppose that a function setenv(s) is to be added to a person-
  277. alized interpreter.
  278.  
  279.    Four things need to be done to incorporate this function in
  280. the personalized interpreter:
  281.  
  282.      1. Provide the code to the function (in, say, setenv.c).
  283.  
  284.      2. Add a line consisting of
  285.  
  286.                 FncDef(setenv,1)         # one argument
  287.  
  288.         to myicon/h/fdefs.h.  This adds the new function to the
  289.         Icon function repertoire.
  290.  
  291.      3. Add setenv.o to the definition of OBJS in
  292.         myicon/pi/Makefile.  This causes setenv.c to be compiled
  293.         and the resulting object file to be loaded with the run-
  294.         time system when a make is performed.
  295.  
  296.      4. Perform a make in myicon/pi to produce new versions of
  297.         picont and piconx in myicon.
  298.  
  299. The function setenv() now can be used like any other built-in
  300. function.
  301.  
  302.    More than one function can be included in a single source
  303. file.  To incorporate these functions in a personalized inter-
  304. preter, an FncDef entry needs to be added for each function, but
  305. only the file need be added to the OBJS list.
  306.  
  307. 2.5__Modifying_the_Existing_Run-Time_System
  308.  
  309.    The use of personalized interpreters is not limited to the
  310. addition of new functions. Any module in the standard run-time
  311. system can be modified as well.
  312.  
  313.    To modify an existing portion of the Icon run-time system,
  314. copy the source code file from v8/src/iconx to myicon/pi.
  315. (Source code for a few run-time routines is placed in myicon/std
  316. when a personalized interpreter is set up. Check this directory
  317. first and use the file there, rather than making another copy in
  318. myicon/pi.) When a source-code file in myicon/pi has been modi-
  319. fied, place it in the OBJS list just like a new file and perform
  320. a make. Note that an entire module must be replaced, even if a
  321. change is made to only one routine.  Any module that is replaced
  322. must contain all the global variables in the original module to
  323. prevent ld(1) from also loading the original module. There is no
  324. way to delete routines from the run-time system.
  325.  
  326.  
  327.  
  328.                               - 4 -
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.    The directory myicon/h contains header files that are included
  338. in various source-code files.  The file myicon/h/rt.h contains
  339. declarations and definitions that are used throughout the run-
  340. time system. This is where information about a new type would be
  341. placed.
  342.  
  343.    Care must be taken when modifying header files so as not to
  344. make changes that would produce inconsistencies between previ-
  345. ously compiled components of the Icon run-time system and new
  346. ones.
  347.  
  348. References
  349.  
  350.  
  351. 1.   R. E. Griswold and M. T. Griswold, The Icon Programming
  352.      Language, Prentice-Hall, Inc., Englewood Cliffs, NJ, 1983.
  353.  
  354. 2.   R. E. Griswold, Version 8 of Icon, The Univ. of Arizona
  355.      Tech. Rep. 90-1, 1990.
  356.  
  357. 3.   R. E. Griswold and M. T. Griswold, The Implementation of the
  358.      Icon Programming Language, Princeton University Press, 1986.
  359.  
  360. 4.   R. E. Griswold, Supplementary Information for the
  361.      Implementation of Version 8 of Icon, The Univ. of Arizona
  362.      Icon Project Document IPD112, 1990.
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                               - 5 -
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.           Appendix - Makefile for Personalized Interpreters
  404.  
  405.  
  406.  
  407.  
  408. Dir=`pwd`
  409. Sdir=`pwd`/../pi
  410.  
  411.  
  412. HDRS=          ../h/config.h ../h/define.h
  413. RHDRS=         ../std/rproto.h ../h/rt.h $(HDRS)
  414. ICHDRS=        ../std/tproto.h ../std/general.h ../std/globals.h $(HDRS)
  415. #
  416. #  To add or replace object files, add their names to the OBJS list below.
  417. #  For example, to add nfncs.o and iolib.o, use:
  418. #
  419. #              OBJS=nfncs.o iolib.o         # this is a sample line
  420. #
  421. #  For each object file added to OBJS, add a dependency line to reflect files
  422. #  that are depended on.  In general, new functions depend on $(RHDRS).
  423. #  For example, if nfncs.c contains new functions, use
  424. #
  425. #              nfncs.o:$(RHDRS)
  426. #
  427. #  Such additions to this Makefile should go at the end.
  428.  
  429.  
  430. OBJS=
  431. LIB=
  432.  
  433.  
  434. ICOBJS= ../std/util.o ../std/tmain.o
  435. RTOBJS= ../std/idata.o $(OBJS)
  436.  
  437.  
  438. pi:            picont piconx ../std/hdr.h
  439.  
  440.  
  441. picont:        ../std/icontlib.a $(ICOBJS) $(RHDRS) ../h/paths.h
  442.                rm -f ../picont picont
  443.                $(CC) $(CFLAGS) -o picont $(ICOBJS) ../std/icontlib.a
  444.                strip picont
  445.                ln picont ../picont
  446.  
  447.  
  448. ../std/ixhdr.o:$(ICHDRS) ../h/header.h ../h/paths.h
  449.                cd ../std; $(CC) -c $(XCFLAGS) \
  450.                  -DIconx="\"$(Sdir)/piconx\"" ixhdr.c
  451.  
  452.  
  453. ../std/iconx.hdr:../std/ixhdr.o
  454.                $(CC) $(XLDFLAGS) ../std/ixhdr.o -o ../std/iconx.hdr
  455.                strip ../std/iconx.hdr
  456.  
  457.  
  458.  
  459.  
  460.                               - 6 -
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. ../std/hdr.h:  $(ICHDRS) ../std/newhdr.c ../std/iconx.hdr
  470.                $(CC) $(XLDFLAGS) -o newhdr ../std/newhdr.c
  471.                ./newhdr <../std/iconx.hdr >../std/hdr.h
  472.                rm -f newhdr iconx.hdr
  473.  
  474.  
  475. piconx:        ../std/rtlib.a $(RTOBJS)
  476.                rm -f ../piconx piconx
  477.                $(CC) $(LDFLAGS) -o piconx $(RTOBJS) ../std/rtlib.a \
  478.                   $(LIB) -lm
  479.                ln piconx ../piconx
  480.  
  481. ../std/idata.o:$(RHDRS) ../h/fdefs.h ../h/odefs.h fdefs.h
  482.                cd ../std; $(CC) -c $(CFLAGS) idata.c
  483.  
  484.  
  485. ../std/util.o: $(ICHDRS) ../std/link.h ../std/sizes.h ../std/trans.h \
  486.                   ../std/tree.h ../std/link.h ../h/fdefs.h fdefs.h
  487.                cd ../std; $(CC) -c $(CFLAGS) util.c
  488.  
  489.  
  490. ../std/tmain.o:$(ICHDRS) ../h/paths.h ../h/fdefs.h fdefs.h
  491.                cd ../std; $(CC) -c -DIconx="\"$(Dir)/../piconx\"" \
  492.                   $(ICOBJS) $(CFLAGS) tmain.c
  493.  
  494.  
  495. Stripx:        piconx picont
  496.                strip piconx picont
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                               - 7 -
  527.  
  528.  
  529.